feat(models): implement Transfer model and TransferStatus enum by angelraph · Pull Request #50 · ShadeProtocol/shade-python

angelraph · 2026-07-25T02:46:20Z

Description

Implements the Transfer model as specced in #40: represents a payout of funds from the merchant wallet to a destination address, following the same pydantic ShadeObject pattern established by Merchant (camelCase API fields aliased to snake_case, extra="allow" for forward compatibility, pydantic.ValidationError wrapped into InvalidRequestError).

src/shade/models/transfer.py: Transfer model with id, source_address, destination_address, amount: Decimal, asset: str, status: TransferStatus, stellar_tx_hash: Optional[str], fee: Optional[Decimal], created_at: datetime.
TransferStatus enum: pending, processing, completed, failed.
asset defaults to "XLM" both when the key is absent and when the API sends an explicit null.
source_address / destination_address are validated as Stellar ed25519 public keys, matching Merchant.address.
Exported from shade.models and the top-level shade package.

Fixes #40

Type of change

New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Added tests/test_transfer.py covering all three acceptance criteria plus edge cases (missing asset/fee, null asset, invalid status, invalid addresses, non-positive amount, negative fee, missing id, unknown-field passthrough, dict round-trip).
pytest -q — 196 passed, 3 skipped (full existing suite + 17 new tests).
flake8 src tests --select=E9,F63,F7,F82 — clean.

Checklist:

My code follows the style guidelines of this project
I have performed a self-review of my own code
My changes generate no new warnings
I have added tests that prove my feature works
New and existing unit tests pass locally with my changes

Summary by CodeRabbit

New Features
- Added support for representing merchant wallet transfers and their lifecycle statuses.
- Transfer details now include source and destination addresses, amount, asset, fees, transaction hash, and creation time.
- Added validation for Stellar addresses, positive amounts, and non-negative fees.
- Transfer data supports automatic field mapping, decimal conversion, and an XLM default asset.

Adds src/shade/models/transfer.py following the pydantic ShadeObject pattern used by Merchant: camelCase API fields are aliased to snake_case, amount/fee are Decimal, status is coerced to a TransferStatus enum, and asset falls back to "XLM" when absent or null. Closes ShadeProtocol#40

coderabbitai · 2026-07-25T02:46:38Z

Warning

Review limit reached

@angelraph, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 49 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3e0d499e-9414-4d74-9469-abb0998df49e

📥 Commits

Reviewing files that changed from the base of the PR and between fca00e2 and fe6635b.

📒 Files selected for processing (2)

src/shade/models/transfer.py
tests/test_transfer.py

📝 Walkthrough

Walkthrough

Changes

Transfer model

Layer / File(s)	Summary
Transfer contract and exports `src/shade/models/transfer.py`, `src/shade/models/__init__.py`, `src/shade/__init__.py`	Adds `TransferStatus`, the aliased `Transfer` model, validation rules, and top-level package exports.
Validation and round-trip coverage `tests/test_transfer.py`	Tests parsing, defaults, enum conversion, validation errors, exported symbols, unknown-key preservation, and camelCase serialization round-trips.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant APIResponse
  participant Transfer.from_dict
  participant PydanticValidators
  APIResponse->>Transfer.from_dict: camelCase transfer payload
  Transfer.from_dict->>PydanticValidators: mapped model fields
  PydanticValidators-->>Transfer.from_dict: validated Transfer instance

Possibly related PRs

ShadeProtocol/shade-python#44: Adds another model and status enum to the shared model exports.
ShadeProtocol/shade-python#45: Updates the same package export surfaces for a new model.

Suggested reviewers: giftexceed

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding the Transfer model and TransferStatus enum.
Description check	✅ Passed	The description includes the summary, issue reference, type of change, and testing details, matching the template well.
Linked Issues check	✅ Passed	The PR implements the Transfer model, fields, enum, and from_dict behavior required by issue `#40`.
Out of Scope Changes check	✅ Passed	The changes stay within the Transfer model scope, with exports and tests supporting the requested feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/shade/models/transfer.py`:
- Around line 50-55: The _default_asset validator currently converts malformed
falsy values such as False and 0 to XLM. Update its fallback condition to apply
only when value is None or an empty string, while preserving valid non-empty
asset strings unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 67522adc-46ce-4f08-85ca-cef358f4e0f6

📥 Commits

Reviewing files that changed from the base of the PR and between 475b970 and fca00e2.

📒 Files selected for processing (4)

src/shade/__init__.py
src/shade/models/__init__.py
src/shade/models/transfer.py
tests/test_transfer.py

Addresses CodeRabbit review on ShadeProtocol#50: the asset default validator only covers None and "" now, so False/0 correctly fail type validation instead of being silently normalized to "XLM".

codebestia

LGTM!
Nice Implementation.
Thank you for your contribution.

coderabbitai Bot reviewed Jul 25, 2026

View reviewed changes

Comment thread src/shade/models/transfer.py Outdated

fix(transfer): don't coerce malformed falsy asset values to XLM

fe6635b

Addresses CodeRabbit review on ShadeProtocol#50: the asset default validator only covers None and "" now, so False/0 correctly fail type validation instead of being silently normalized to "XLM".

codebestia approved these changes Jul 25, 2026

View reviewed changes

codebestia merged commit 264d02d into ShadeProtocol:main Jul 25, 2026
2 checks passed

grantfox-oss Bot mentioned this pull request Jul 25, 2026

Implement Transfer model #40

Closed

coderabbitai Bot mentioned this pull request Aug 3, 2026

Add Payment model with Decimal amounts and PaymentStatus. #44

Closed

10 tasks

Navigation Menu

Uh oh!

feat(models): implement Transfer model and TransferStatus enum - #50

feat(models): implement Transfer model and TransferStatus enum#50
codebestia merged 2 commits into
ShadeProtocol:mainfrom
angelraph:feat/transfer-model

angelraph commented Jul 25, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 25, 2026 •

edited

Loading

Review limit reached

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

codebestia left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

angelraph commented Jul 25, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Checklist:

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codebestia left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

angelraph commented Jul 25, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 25, 2026 •

edited

Loading